import { Steps, Callout } from 'nextra/components';
import { Adopters } from '@/components/introduction/Adopters';

# es-hangul 소개

[![npm version](https://img.shields.io/npm/v/es-hangul?color=000&labelColor=000&logo=npm&label=)](https://www.npmjs.com/package/es-hangul)
[![npm](https://img.shields.io/npm/dm/es-hangul?color=000&labelColor=000)](https://www.npmjs.com/package/es-hangul)

한글을 다루는 제품을 개발할 때, 초성 검색, 정확한 조사 붙이기와 같은 작업을 수행해야 할 경우가 많습니다. 그 외로 초성, 중성, 종성 등의 한글을 분리하거나 결합해야 하는 경우도 있죠. `es-hangul`은 이렇게 비즈니스에서 반복적으로 발생하는 한글 관련한 기능을 쉽고 빠르게 구현할 수 있도록 돕습니다.

`es-hangul`은 초, 중, 종성 추출과 변환 등 복잡한 한글 문자열 처리를 위한 인터페이스를 제공합니다. `es-hangul`의 기능과 JavaScript 기본 메소드를 조합하면 모든 케이스의 한글 문자열 처리를 기대할 수 있습니다.

<br />

## 어떤 이유로 사용하나요?

<Steps>

### 가볍습니다 (Tree-shakable)

ECMAScript Modules를 이용하여 사용하는 함수만 애플리케이션에 포함할 수 있습니다. 예를 들어, [`josa`](./api/core/josa) 함수를 사용하는 경우, 해당 함수와 연관된 로직만 애플리케이션에 포함됩니다.
또한 한글을 다루는 데에 필요한 최소한의 코드를 제공함으로써, 사용자가 내려받는 JavaScript의 크기를 줄일 수 있습니다.
[![es-hangul's bundle size](https://deno.bundlejs.com/?q=es-hangul&badge=detailed)](https://bundlejs.com/?q=es-hangul)

### 신뢰할 수 있습니다

우리는 커버리지 100%를 목표로 모든 기능을 테스트하기 위해 [노력하고 있습니다](./advantages/reliability).
[![codecov](https://codecov.io/gh/toss/es-hangul/branch/main/graph/badge.svg?token=토큰추가가필요합니다)](https://codecov.io/gh/toss/es-hangul)

### TypeScript를 지원합니다

[강력한 타입을 제공](./advantages/type-support)해 개발 단계에서 타입 오류를 쉽게 감지할 수 있습니다.

### 한글을 위한 모든 인터페이스를 제공하는 것을 목표합니다

다양한 애플리케이션에서 편리하게 사용할 수 있는 [현대적인 API](./api/core/assemble)를 제공합니다.

#### 초성 검색 ([getChoseong](./api/core/getChoseong))

특정 단어에서 초성을 얻을 수 있습니다. 예를 들어, '라면'이라는 단어가 'ㄹㅁ'으로 시작하는 초성을 포함하는지 쉽게 알 수 있습니다.

```tsx /getChoseong/
import { getChoseong } from 'es-hangul';

const searchWord = '라면';
const userInput = 'ㄹㅁ';

const result = getChoseong(searchWord); // ㄹㅁ

// 검색어의 초성과 사용자 입력 초성이 일치하는지 확인
if (result === userInput) {
  something();
}
```

#### 초/중/종성 분해 ([disassemble](./api/core/disassemble))

주어진 한글 문자열을 초성, 중성, 종성으로 분해하여 배열 형태로 반환해 문자열을 더 세밀하게 분석하거나 수정할 수 있습니다.

```tsx /disassemble/
import { disassemble } from 'es-hangul';

const word = '안녕하세요';
const disassembled = disassemble(word);
console.log(disassembled); // 'ㅇㅏㄴㄴㅕㅇㅎㅏㅅㅔㅇㅛ'
```

#### 조사 처리 ([josa](./api/core/josa))

단어의 마지막 글자가 받침이 있는지 여부에 따라 적절한 조사를 자동으로 선택합니다.

```tsx /josa/
import { josa } from 'es-hangul';

const word1 = '사과';
const sentence1 = josa(word1, '을/를') + ' 먹었습니다.';
console.log(sentence1); // '사과를 먹었습니다.'

const word2 = '바나나';
const sentence2 = josa(word2, '이/가') + ' 맛있습니다.';
console.log(sentence2); // '바나나가 맛있습니다.'
```

### 매우 빠릅니다

`es-hangul`은 **한글 조합** 및 **분해** 같은 복잡한 작업을 놀라운 속도로 수행하는 **최고의 성능**을 자랑합니다.<br/>
다른 라이브러리와의 [벤치마크](./advantages/benchmark) 테스트 결과, `es-hangul`이 **압도적으로 빠른 성능**을 보여주었습니다

<Callout type="info">

한글을 잘 다루기 위한 좋은 아이디어가 있다면 알려주세요. [GitHub Issue로 기능 제안하기](https://github.com/toss/es-hangul/issues/new?assignees=&labels=feature&projects=&template=feature_request.yml&title=%5BFeature%5D%3A)

</Callout>

</Steps>

## 어떤 곳에서 사용하나요?

<br />

<Adopters />

<Callout type="info">

es-hangul을 사용하는 조직의 로고를 추가해주세요. 우리는 이 라이브러리를 여러분과 함께 만들어 갑니다. [GitHub PR로 사용자 추가하기](https://github.com/toss/es-hangul/blob/main/docs/src/components/introduction/Adopters.tsx)

</Callout>
